[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Overview

Here is a brief summary of how to invoke sde-as. For details, see section Comand-Line Options.

 
sde-as [ -a[cdhlns][=file] ] [ -D ]  [ --defsym sym=val ]
 [ -f ] [ --gstabs ] [ --gdwarf2 ] [ --help ] [ -I dir ] [ -J ] [ -K ] [ -L ]
 [ --keep-locals ] [ -o objfile ] [ -R ] [ --statistics ] [ -v ]
 [ -version ] [ --version ] [ -W ] [ --warn ] [ --fatal-warnings ] 
 [ -w ] [ -X ] [ -x ] [ -Z ]
 [ -EL ] [ -EB ] [ -G num ] [ -O[num] ]
 [ -mcpu=cpu ] [ -mabi=abi ]
 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -mips4 ] [ -mips5 ]
 [ -mips32 ] [ -mips32r2 ] [ -mips64 ] [ -mips64r2 ]
 [ -mips16 ] [ -mips16e ]
 [ -msmartmips ] [ -mips3D ]
 [ -mgp32 ] [ -mgp64 ] [ -mfp32 ] [ -mfp64 ]
 [ -mhard-float ]  [ -msingle-float ]
 [ -msoft-float ]  [ -mno-float ]
 [ -mno-fix-cw4010 ] [ -mno-fix-vr4300 ] [ -mno-fix-r4000 ]
 [ -mdiv-checks ] [ -mno-div-checks ] 
 [ -membedded-data ] [ -mno-gpconst ]
 [ --trap ] [ --no-break ] [ --break ] [ --no-trap ]
 [ -KPIC ] [ -call_shared ] [ -non_shared ] [ -xgot ]
 [ -membedded-pic ]
 [ -- | files ... ]

-a[cdhlmns]
Turn on listings, in any of a variety of ways:

-ac
omit false conditionals

-ad
omit debugging directives

-ah
include high-level source

-al
include assembly

-am
include macro expansions

-an
omit forms processing

-as
include symbols

=file
set the name of the listing file

You may combine these options; for example, use `-aln' for assembly listing without forms processing. The `=file' option, if used, must be the last one. By itself, `-a' defaults to `-ahls'.

-D
Ignored. This option is accepted for script compatibility with calls to other assemblers.

--defsym sym=value
Define the symbol sym to be value before assembling the input file. value must be an integer constant. As in C, a leading `0x' indicates a hexadecimal value, and a leading `0' indicates an octal value.

-f
"fast"---skip whitespace and comment preprocessing (assume source is compiler output).

--gstabs
Generate stabs debugging information for each assembler line. This may help debugging assembler code, if the debugger can handle it.

--gdwarf2
Generate DWARF2 debugging information for each assembler line. This may help debugging assembler code, if the debugger can handle it.

--help
Print a summary of the command line options and exit.

-I dir
Add directory dir to the search list for .include directives.

-J
Don't warn about signed overflow.

-K
This option is accepted but has no effect on the MIPS family.

-L
--keep-locals
Keep (in the symbol table) local symbols. On traditional a.out systems these start with `L', but different systems have different local label prefixes.

-o objfile
Name the object-file output from sde-as objfile.

-R
Fold the data section into the text section.

--statistics
Print the maximum space (in bytes) and total time (in seconds) used by assembly.

--strip-local-absolute
Remove local absolute symbols from the outgoing symbol table.

-v
-version
Print the as version.

--version
Print the as version and exit.

-W
--no-warn
Suppress warning messages.

-X
--fatal-warnings
Treat warnings as errors.

--warn
Don't suppress warning messages or treat them as errors.

-w
Ignored.

-x
Ignored.

-X
Treat warnings as errors.

-Z
Generate an object file even after errors.

-- | files ...
Standard input, or source files to assemble.

The following options are available when sde-as is configured for a MIPS processor. For a full description of these arguments, see Assembler options.

-G num
This option sets the largest size of an object that can be referenced implicitly with the gp register. Set to zero to disable.

-O
-Onum
Selects the assembler optimization level.

-EB
-EL
Use `-EB' to select big-endian output, and `-EL' for little-endian.

-mcpu=cpu
Generate code for a particular MIPS CPU.

-mips1, -mips2, -mips3, -mips4, -mips5
-mips32, -mips32r2, -mips64, -mips64r2
Generate code for a particular MIPS ISA (Instruction Set Architecture) level.

-mips16
Enables the MIPS16 compressed instruction set extension. This will not generate MIPS16 code automatically, you must include `.set mips16' and `.set nomips16' directives around sections of assembler code which are written for MIPS16. Most users will never, and should never, write MIPS16 assembler code. MIPS16 is meant as an intermediate code generated by the compiler to reduce code size -- possibly at the cost of some speed. MIPS16 CPUs always run the normal 32-bit MIPS instruction set as well, which is usually a better choice for assembler modules.

-mips16e
Enables the enhanced MIPS16e compressed instruction set extension. See `-mips16' above for usage.

-msmartmips
Enables the SmartMIPS extension to the MIPS32 instruction set.

-mips3D
Enables the MIPS-3D extension to the MIPS64 instruction set.

-mabi=32|o64|n32|64|eabi|meabi
Generate code for the indicated ABI.

-mgp32
Assume that the 32 general purpose registers are 32 bits wide.

-mgp64
Assume that the 32 general purpose registers are 64 bits wide.

-mfp32
Assume that 32 32-bit floating point registers are available (equivalent to 16 64-bit registers, when used in pairs).

-mfp64
Assume that 32 64-bit floating point registers are available.

-mhard-float
Enable use of the floating-point coprocessor instructions. This is the default.

-msingle-float
Enable use of the floating-point coprocessor instructions, but only for single-precision arithmetic.

-msoft-float
-mno-float
Generate an error message if any floating-point instructions are used.

-mno-div-checks
-mdiv-checks
Disable (or enable) the automatic generation of code to check for division by zero, or divide overflow.

--trap
--no-break
Generate code which takes a trap exception rather than a break exception when multiply or divide overflow error is detected.

--break
--no-trap
Generate code to take a break exception rather than a trap exception when an divide or multiply overflow is detected. This is the default.

-KPIC
-call_shared
Enable the generation of MIPS/abi position-independent code.

-xgot
Generate assume a "large" global offset table references for MIPS/abi code.

-non_shared
Disable position-independent code. This is the default.

-membedded-pic
Generate PIC code suitable for some embedded systems. Not supported on MIPS SDE.

-membedded-data
-mno-gpconst
Place floating-point immediates in read-only data section.

-mno-fix-cw4010
Disables assembler workaround for early versions of the LSI CW4010 CPU.

-mno-fix-vr4300
Disables assembler workaround for early versions of the Vr4300 CPU.

-mno-fix-r4000
Disables assembler workaround for early versions of the R4000.

1.1 Structure of this Manual  
1.2 The GNU Assembler  
1.3 Object File Formats  
1.4 Command Line  
1.5 Input Files  
1.6 Output (Object) File  
1.7 Error and Warning Messages  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Structure of this Manual

This manual is intended to describe what you need to know to use GNU sde-as. We cover the syntax expected in source files, including notation for symbols, constants, and expressions; the directives that sde-as understands; and of course how to invoke sde-as.

We also cover special features in the MIPS configuration of sde-as, including assembler directives.

On the other hand, this manual is not intended as an introduction to programming in assembly language--let alone programming in general! In a similar vein, we make no attempt to introduce the machine architecture; we do not describe the instruction set, standard mnemonics, registers or addressing modes that are standard to a particular architecture.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 The GNU Assembler

GNU as is really a family of assemblers. This manual describes sde-as, a member of that family which is configured for the MIPS architectures. If you use (or have used) the GNU assembler on one architecture, you should find a fairly similar environment when you use it on another architecture. Each version has much in common with the others, including object file formats, most assembler directives (often called pseudo-ops) and assembler syntax.

sde-as is primarily intended to assemble the output of the GNU C compiler sde-gcc for use by the linker sde-ld. Nevertheless, we've tried to make sde-as assemble correctly everything that other assemblers for the same machine would assemble.

Unlike older assemblers, sde-as is designed to assemble a source program in one pass of the source file. This has a subtle impact on the .org directive (see section .org).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Object File Formats

The GNU assembler can be configured to produce several alternative object file formats. For the most part, this does not affect how you write assembly language programs; but directives for debugging symbols are typically different in different file formats. See section Symbol Attributes. On the MIPS, sde-as is configured to produce ELF format object files.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Command Line

After the program name sde-as, the command line may contain options and file names. Options may appear in any order, and may be before, after, or between file names. The order of file names is significant.

`--' (two hyphens) by itself names the standard input file explicitly, as one of the files for sde-as to assemble.

Except for `--' any command line argument that begins with a hyphen (`-') is an option. Each option changes the behavior of sde-as. No option changes the way another option works. An option is a `-' followed by one or more letters; the case of the letter is important. All options are optional.

Some options expect exactly one file name to follow them. The file name may either immediately follow the option's letter (compatible with older assemblers) or it may be the next command argument (GNU standard). These two command lines are equivalent:

 
sde-as -o my-object-file.o mumble.s
sde-as -omy-object-file.o mumble.s


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Input Files

We use the phrase source program, abbreviated source, to describe the program input to one run of sde-as. The program may be in one or more files; how the source is partitioned into files doesn't change the meaning of the source.

The source program is a concatenation of the text in all the files, in the order specified.

Each time you run sde-as it assembles exactly one source program. The source program is made up of one or more files. (The standard input is also a file.)

You give sde-as a command line that has zero or more input file names. The input files are read (from left file name to right). A command line argument (in any position) that has no special meaning is taken to be an input file name.

If you give sde-as no file names it attempts to read one input file from the sde-as standard input, which is normally your terminal. You may have to type ctl-D to tell sde-as there is no more program to assemble.

Use `--' if you need to explicitly name the standard input file in your command line.

If the source is empty, sde-as produces a small, empty object file.

Filenames and Line-numbers

There are two ways of locating a line in the input file (or files) and either may be used in reporting error messages. One way refers to a line number in a physical file; the other refers to a line number in a "logical" file. See section Error and Warning Messages.

Physical files are those files named in the command line given to sde-as.

Logical files are simply names declared explicitly by assembler directives; they bear no relation to physical files. Logical file names help error messages reflect the original source file, when sde-as source is itself synthesized from other files. sde-as understands the `#' directives emitted by the sde-gcc preprocessor. See also .file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Output (Object) File

Every time you run sde-as it produces an output file, which is your assembly language program translated into numbers. This file is the object file. Its default name is a.out. You can give it another name by using the -o option. Conventionally, object file names end with `.o'. The default name is used for historical reasons: older assemblers were capable of assembling self-contained programs directly into a runnable program. (For some formats, this isn't currently possible, but it can be done for the a.out format.)

The object file is meant for input to the linker sde-ld. It contains assembled program code, information to help sde-ld integrate the assembled program into a runnable file, and (optionally) symbolic information for the debugger.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Error and Warning Messages

sde-as may write warnings and error messages to the standard error file (usually your terminal). This should not happen when a compiler runs sde-as automatically. Warnings report an assumption made so that sde-as could keep assembling a flawed program; errors report a grave problem that stops the assembly.

Warning messages have the format

 
file_name:NNN:Warning Message Text

(where NNN is a line number). If a logical file name has been given (see section .file) it is used for the filename, otherwise the name of the current input file is used. If a logical line number was given (see section .line) then it is used to calculate the number printed, otherwise the actual line in the current source file is printed. The message text is intended to be self explanatory (in the grand Unix tradition).

Error messages have the format

 
file_name:NNN:FATAL:Error Message Text
The file name and line number are derived as for warning messages. The actual message text may be rather less explanatory because many of them aren't supposed to happen.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by MIPS Technologies, Inc. on September, 12 2003 using texi2html